package de.pyranja.storage;

import java.io.InputStream;

import com.google.common.util.concurrent.ListenableFuture;

import de.pyranja.storage.exception.BinaryStorageException;
import de.pyranja.storage.exception.BlobNotFoundException;

/**
 * A storage for binary data. 
 * @author Chris Borckholder
 */
public interface BinaryStorage {
	
	/**
	 * Stores the data from the passed stream.
	 * @param data to be stored
	 * @return identifier of stored data
	 * @throws BinaryStorageException if an IO error occured
	 */
	Blob store(InputStream data);
	
	/**
	 * Opens a stream to the data identified by the specified {@link BlobID}.
	 * @param id of desired data
	 * @return a stream to the data
	 * @throws BlobNotFoundException if the given blob is not known
	 */
	InputStream fetch(String id) throws BlobNotFoundException;
	
	/**
	 * Creates a strong reference to the data identified by the specified {@link 
	 * BlobID}.
	 * @param id of existing data
	 * @return true if referencing succeeded
	 * @throws BlobNotFoundException if the given blob is not known
	 */
	ListenableFuture<String> claim(String id) throws BlobNotFoundException;
	
	/**
	 * Releases a strong reference to the data identified by the specified {@link
	 * BlobID}.
	 * @param id of released data
	 * @return true if id existed and was released, false if id did not exist
	 */
	ListenableFuture<String> release(String id);
}
